/**
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * SPDX-License-Identifier: Apache-2.0.
 */

#ifndef AWS_IO_FUTURE_H
#define AWS_IO_FUTURE_H

/*

--------------------------------------------------------------------------------
INTRO
--------------------------------------------------------------------------------
An aws_future is used to deliver the result of an asynchronous function.

When an async function is called, it creates a future and returns it to the caller.
When the async work is finished, it completes the future by setting an error or result value.
The caller waits until the future is done, checks for error, and then gets
the result if everything was OK. Typically, the caller waits by registering
a callback that the future invokes when it's done. There are many different
ways to register callbacks, depending on what thread you want it to fire on.

If result type T has a "destructor" (clean_up(), destroy(), or release() function),
then the future has set_result_by_move() and get_result_by_move() functions
that explicitly transfer ownership to and from the future.
If the future dies, and still "owns" the resource, it calls the destructor.
If T has no destructor, then the future has set_result() and get_result()
functions that simply copy T by value.

Macros are used to define a type-safe API for each result type T,
similar to C++ templates. This makes the API hard to browse, so functions
are documented in comments below.

--------------------------------------------------------------------------------
API (common to all aws_future<T>)
    The set/get result functions are mildly different based on T's
    destructor type, and are documented later.
--------------------------------------------------------------------------------

// Create a new future, with refcount of 1.
struct aws_future_T *aws_future_T_new(struct aws_allocator *alloc);

// Increment the refcount.
// You can pass NULL (has no effect).
// Returns the same pointer that was passed in.
struct aws_future_T *aws_future_T_acquire(struct aws_future_T *future);

// Decrement the refcount.
// You can pass NULL (has no effect).
// Always returns NULL.
struct aws_future_T *aws_future_T_release(struct aws_future_T *future);

// Set future as done, with an error_code.
// If the future is already done this call is ignored.
void aws_future_T_set_error(struct aws_future_T *future, int error_code);

// Return whether the future is done.
bool aws_future_T_is_done(const struct aws_future_T *future);

// Get the error-code of a completed future.
// If 0 is returned, then the future completed successfully,
// you may now get the result.
//
// WARNING: You MUST NOT call this until the future is done.
int aws_future_T_get_error(const struct aws_future_T *future);

// Register callback to be invoked when the future completes.
//
// If the future is already done, the callback runs synchronously on the calling thread.
// If the future isn't done yet, the callback is registered, and it
// will run synchronously on whatever thread completes the future.
//
// WARNING: You MUST NOT register more than one callback.
void aws_future_T_register_callback(struct aws_future_T *future, aws_future_callback_fn *on_done, void *user_data);

// If the future isn't done yet, then register the completion callback.
//
// Returns true if the callback was registered,
// or false if the future is already done.
//
// Use this when you can't risk the callback running synchronously.
// For example: If you're calling an async function repeatedly,
// and synchronous completion could lead to stack overflow due to recursion.
// Or if you are holding a non-recursive mutex, and the callback also
// needs the mutex, and an immediate callback would deadlock.
//
// WARNING: You MUST NOT register more than one callback.
bool aws_future_T_register_callback_if_not_done(
    struct aws_future_T *future,
    aws_future_callback_fn *on_done,
    void *user_data);

// Register completion callback to run async on an event-loop thread.
//
// When the future completes, the callback is scheduled to run as an event-loop task.
//
// Use this when you want the callback to run on the event-loop's thread,
// or to ensure the callback runs async even if the future completed synchronously.
//
// WARNING: You MUST NOT register more than one callback.
void aws_future_T_register_event_loop_callback(
    struct aws_future_T *future,
    struct aws_event_loop *event_loop,
    aws_future_callback_fn *on_done,
    void *user_data);

// Register completion callback to run async on an aws_channel's thread.
//
// When the future completes, the callback is scheduled to run as a channel task.
//
// Use this when you want the callback to run on the channel's thread,
// or to ensure the callback runs async even if the future completed synchronously.
//
// WARNING: You MUST NOT register more than one callback.
void aws_future_T_register_channel_callback(
    struct aws_future_T *future,
    struct aws_channel *channel,
    aws_future_callback_fn *on_done,
    void *user_data);

// Wait (up to timeout_ns) for future to complete.
// Returns true if future completes in this time.
// This blocks the current thread. It is dangerous to use anywhere except
// the main thread of simple programs or tests.
bool aws_future_T_wait(struct aws_future_T *future, uint64_t timeout_ns);

--------------------------------------------------------------------------------
AWS_FUTURE_T_BY_VALUE set/get API
    Where T is stored by value, with no destructor.
    Use with simple types like bool, size_t, enums, etc.
--------------------------------------------------------------------------------

// Set the result.
//
// If the future is already done this call is ignored.
void aws_future_T_set_result(const struct aws_future_T *future, T result);

// Get the result of a completed future.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
T aws_future_T_get_result(const struct aws_future_T *future);

--------------------------------------------------------------------------------
AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP set/get API
    Where T is stored by value, with destructor like: void aws_T_clean_up(T*)
    Use with types like aws_byte_buf.
--------------------------------------------------------------------------------

// Set the result, transferring ownership.
//
// The memory at `value_address` is memcpy'd into the future,
// and then zeroed out to help prevent accidental reuse.
// It is safe to call this multiple times. If the future is already done,
// the new result is destroyed instead of saved.
void aws_future_T_set_result_by_move(struct aws_future_T *future, T *value_address);

// Get the result, transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T aws_future_T_get_result_by_move(struct aws_future_T *future);

// Get the result, without transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T* aws_future_T_peek_result(const struct aws_future_T *future);

--------------------------------------------------------------------------------
AWS_FUTURE_T_POINTER_WITH_DESTROY set/get API
    Where T is stored by pointer, with destructor like: void aws_T_destroy(T*)
    Use with types like aws_string.
--------------------------------------------------------------------------------

// Set the result, transferring ownership.
//
// The value at `pointer_address` is copied into the future,
// and then set NULL to prevent accidental reuse.
// If the future is already done, this new result is destroyed instead of saved.
void aws_future_T_set_result_by_move(struct aws_future_T *future, T **pointer_address);

// Get the result, transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T* aws_future_T_get_result_by_move(struct aws_future_T *future);

// Get the result, without transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T* aws_future_T_peek_result(const struct aws_future_T *future);

--------------------------------------------------------------------------------
AWS_FUTURE_T_POINTER_WITH_RELEASE set/get API
    Where T is stored by pointer, with destructor like: T* aws_T_release(T*)
    Use with types like aws_http_message
--------------------------------------------------------------------------------

// Set the result, transferring ownership.
//
// The value at `pointer_address` is copied into the future,
// and then set NULL to prevent accidental reuse.
// If the future is already done, this new result is destroyed instead of saved.
void aws_future_T_set_result_by_move(struct aws_future_T *future, T **pointer_address);

// Get the result, transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T* aws_future_T_get_result_by_move(struct aws_future_T *future);

// Get the result, without transferring ownership.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
// WARNING: You MUST NOT call this multiple times.
T* aws_future_T_peek_result(const struct aws_future_T *future);

--------------------------------------------------------------------------------
AWS_FUTURE_T_POINTER set/get API
    Where T is stored by pointer, with no destructor.
    No known use cases, but it's here for completeness.
--------------------------------------------------------------------------------

// Set the result.
//
// If the future is already done this call is ignored.
void aws_future_T_set_result(const struct aws_future_T *future, T *result);

// Get the result of a completed future.
//
// WARNING: You MUST NOT call this until the future is done.
// WARNING: You MUST NOT call this unless get_error() returned 0.
T* aws_future_T_get_result(const struct aws_future_T *future);

--------------------------------------------------------------------------------
DEFINING NEW aws_future<T>
--------------------------------------------------------------------------------

Macros are used to define a type-safe API for each result type T, similar to C++ templates.

Use the _DECLARATION() macro in the same header where T's API is declared.
Use the _IMPLEMENTATION() macro in the corresponding .c file.
The macros can only be used once for each type T,
so it makes sense to put it where T is declared.
If T lives in a single .c file and has no header, you can simply use the
_IMPLEMENTATION() macro without a _DECLARATION().

You must pick the right macros for your particular T, based on whether T is stored
by value or by pointer, and which type of "destructor" function it has:

- AWS_FUTURE_T_BY_VALUE: A future that holds a simple T by value, that needs no destructor.
    Use with types like bool, size_t, enums, etc.
    Example:
         AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API)
         AWS_FUTURE_T_BY_VALUE_IMPLEMENTATION(aws_future_size, size_t)

- AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP: A future that holds T by value, with destructor like: void aws_T_clean_up(T*)
    Use with types like aws_byte_buf.
    Example:
        AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP_DECLARATION(aws_future_byte_buf, aws_byte_buf, AWS_IO_API)
        AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP_IMPLEMENTATION(aws_future_byte_buf, aws_byte_buf,
                                                           aws_byte_buf_clean_up);
- AWS_FUTURE_T_POINTER_WITH_DESTROY: A future that holds T*, with destructor like: void aws_T_destroy(T*)
    Use with types like aws_string.
    Example:
        AWS_FUTURE_T_POINTER_WITH_DESTROY_DECLARATION(aws_future_string, aws_string, AWS_IO_API)
        AWS_FUTURE_T_POINTER_WITH_DESTROY_DECLARATION(aws_future_string, aws_string, AWS_IO_API)

- AWS_FUTURE_T_POINTER_WITH_RELEASE: A future that holds T*, with destructor like: T* aws_T_release(T*)
    Use with types like aws_http_message
    Example:
        AWS_FUTURE_T_POINTER_WITH_RELEASE_DECLARATION(aws_future_http_message, struct aws_http_message,
                                                      AWS_HTTP_API)
        AWS_FUTURE_T_POINTER_WITH_RELEASE_IMPLEMENTATION(aws_future_http_message, struct aws_http_message,
                                                        aws_http_message_release)

- AWS_FUTURE_T_POINTER: A future that holds T*, with no destructor.
     No known use cases, but it's here for completeness.
     Example:
         AWS_FUTURE_T_POINTER_DECLARATION(aws_future_file. FILE, AWS_IO_API)
         AWS_FUTURE_T_POINTER_IMPLEMENTATION(aws_future_file. FILE)

--------------------------------------------------------------------------------
DESIGN (if you're curious)
--------------------------------------------------------------------------------
This class was developed to give the user more control over how the completion
callback is invoked. In the past, we passed completion callbacks to the async
function. But this could lead to issues when an async function "sometimes"
completed synchronously and "sometimes" completed async. The async function
would need to stress about how to schedule the callback so it was always async,
or more typically just invoke it whenever and leave the caller to figure it out.

This class is also an experiment with "templates/generics in C".
In order to make the class type-safe, we use macros to define a unique
API for each result type T we need to store in a future.
If we refer to aws_future<struct aws_byte_buf>, we mean a struct named
aws_future_byte_buf, which stores an aws_byte_buf by value.
This could lead to code bloat, but the type-safety seems worth it.

future is defined in aws-c-io, instead of aws-c-common, so it can
easily integrate with aws_event_loop and aws_channel.

It's legal to call set_error() or set_result() multiple times.
If the future is already done, it ignores the call.
If result T has a destructor, the new result is immediately freed instead of saved.
This design lets us deal with ambiguity where it's not 100% certain whether a handoff occurred.
For example: if we call from C->Java and an exception is thrown,
it's not clear whether Java got the handoff. In this case, we can safely
call set_error(), completing the future if necessary,
or being ignored if the future was already done.

*/

#include <aws/io/io.h>

AWS_PUSH_SANE_WARNING_LEVEL

struct aws_channel;
struct aws_event_loop;
struct aws_future_impl;

/** Completion callback for aws_future<T> */
typedef void(aws_future_callback_fn)(void *user_data);

typedef void(aws_future_impl_result_clean_up_fn)(void *result_addr);
typedef void(aws_future_impl_result_destroy_fn)(void *result);
typedef void *(aws_future_impl_result_release_fn)(void *result);

AWS_EXTERN_C_BEGIN

AWS_IO_API
struct aws_future_impl *aws_future_impl_new_by_value(struct aws_allocator *alloc, size_t sizeof_result);

AWS_IO_API
struct aws_future_impl *aws_future_impl_new_by_value_with_clean_up(
    struct aws_allocator *alloc,
    size_t sizeof_result,
    aws_future_impl_result_clean_up_fn *result_clean_up);

AWS_IO_API
struct aws_future_impl *aws_future_impl_new_pointer(struct aws_allocator *alloc);

AWS_IO_API
struct aws_future_impl *aws_future_impl_new_pointer_with_destroy(
    struct aws_allocator *alloc,
    aws_future_impl_result_destroy_fn *result_destroy);

AWS_IO_API
struct aws_future_impl *aws_future_impl_new_pointer_with_release(
    struct aws_allocator *alloc,
    aws_future_impl_result_release_fn *result_release);

AWS_IO_API
struct aws_future_impl *aws_future_impl_release(struct aws_future_impl *promise);

AWS_IO_API
struct aws_future_impl *aws_future_impl_acquire(struct aws_future_impl *promise);

AWS_IO_API
void aws_future_impl_set_error(struct aws_future_impl *promise, int error_code);

AWS_IO_API
void aws_future_impl_set_result_by_move(struct aws_future_impl *promise, void *src_address);

AWS_IO_API
bool aws_future_impl_is_done(const struct aws_future_impl *future);

AWS_IO_API
void aws_future_impl_register_callback(
    struct aws_future_impl *future,
    aws_future_callback_fn *on_done,
    void *user_data);

AWS_IO_API
bool aws_future_impl_register_callback_if_not_done(
    struct aws_future_impl *future,
    aws_future_callback_fn *on_done,
    void *user_data);

AWS_IO_API
void aws_future_impl_register_event_loop_callback(
    struct aws_future_impl *future,
    struct aws_event_loop *event_loop,
    aws_future_callback_fn *on_done,
    void *user_data);

AWS_IO_API
void aws_future_impl_register_channel_callback(
    struct aws_future_impl *future,
    struct aws_channel *channel,
    aws_future_callback_fn *on_done,
    void *user_data);

AWS_IO_API
bool aws_future_impl_wait(const struct aws_future_impl *future, uint64_t timeout_ns);

AWS_IO_API
int aws_future_impl_get_error(const struct aws_future_impl *future);

AWS_IO_API
void *aws_future_impl_get_result_address(const struct aws_future_impl *future);

AWS_IO_API
void aws_future_impl_get_result_by_move(struct aws_future_impl *future, void *dst_address);

/* Common beginning to all aws_future<T> declarations */
#define AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API) struct FUTURE;

/* Common beginning to all aws_future<T> implementations */
#define AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)

/* Common end to all aws_future<T> declarations */
#define AWS_FUTURE_T_DECLARATION_END(FUTURE, API)                                                                      \
    API struct FUTURE *FUTURE##_acquire(struct FUTURE *future);                                                        \
    API struct FUTURE *FUTURE##_release(struct FUTURE *future);                                                        \
    API void FUTURE##_set_error(struct FUTURE *future, int error_code);                                                \
    API bool FUTURE##_is_done(const struct FUTURE *future);                                                            \
    API int FUTURE##_get_error(const struct FUTURE *future);                                                           \
    API void FUTURE##_register_callback(struct FUTURE *future, aws_future_callback_fn *on_done, void *user_data);      \
    API bool FUTURE##_register_callback_if_not_done(                                                                   \
        struct FUTURE *future, aws_future_callback_fn *on_done, void *user_data);                                      \
    API void FUTURE##_register_event_loop_callback(                                                                    \
        struct FUTURE *future, struct aws_event_loop *event_loop, aws_future_callback_fn *on_done, void *user_data);   \
    API void FUTURE##_register_channel_callback(                                                                       \
        struct FUTURE *future, struct aws_channel *channel, aws_future_callback_fn *on_done, void *user_data);         \
    API bool FUTURE##_wait(struct FUTURE *future, uint64_t timeout_ns);

/* Common end to all aws_future<T> implementations */
#define AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)                                                                        \
    struct FUTURE *FUTURE##_acquire(struct FUTURE *future) {                                                           \
        return (struct FUTURE *)aws_future_impl_acquire((struct aws_future_impl *)future);                             \
    }                                                                                                                  \
                                                                                                                       \
    struct FUTURE *FUTURE##_release(struct FUTURE *future) {                                                           \
        return (struct FUTURE *)aws_future_impl_release((struct aws_future_impl *)future);                             \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_error(struct FUTURE *future, int error_code) {                                                   \
        aws_future_impl_set_error((struct aws_future_impl *)future, error_code);                                       \
    }                                                                                                                  \
                                                                                                                       \
    bool FUTURE##_is_done(const struct FUTURE *future) {                                                               \
        return aws_future_impl_is_done((const struct aws_future_impl *)future);                                        \
    }                                                                                                                  \
                                                                                                                       \
    int FUTURE##_get_error(const struct FUTURE *future) {                                                              \
        return aws_future_impl_get_error((const struct aws_future_impl *)future);                                      \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_register_callback(struct FUTURE *future, aws_future_callback_fn *on_done, void *user_data) {         \
        aws_future_impl_register_callback((struct aws_future_impl *)future, on_done, user_data);                       \
    }                                                                                                                  \
                                                                                                                       \
    bool FUTURE##_register_callback_if_not_done(                                                                       \
        struct FUTURE *future, aws_future_callback_fn *on_done, void *user_data) {                                     \
                                                                                                                       \
        return aws_future_impl_register_callback_if_not_done((struct aws_future_impl *)future, on_done, user_data);    \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_register_event_loop_callback(                                                                        \
        struct FUTURE *future, struct aws_event_loop *event_loop, aws_future_callback_fn *on_done, void *user_data) {  \
                                                                                                                       \
        aws_future_impl_register_event_loop_callback(                                                                  \
            (struct aws_future_impl *)future, event_loop, on_done, user_data);                                         \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_register_channel_callback(                                                                           \
        struct FUTURE *future, struct aws_channel *channel, aws_future_callback_fn *on_done, void *user_data) {        \
                                                                                                                       \
        aws_future_impl_register_channel_callback((struct aws_future_impl *)future, channel, on_done, user_data);      \
    }                                                                                                                  \
                                                                                                                       \
    bool FUTURE##_wait(struct FUTURE *future, uint64_t timeout_ns) {                                                   \
        return aws_future_impl_wait((struct aws_future_impl *)future, timeout_ns);                                     \
    }

/**
 * Declare a future that holds a simple T by value, that needs no destructor.
 * Use with types like bool, size_t, etc.
 *
 * See top of future.h for docs.
 */
#define AWS_FUTURE_T_BY_VALUE_DECLARATION(FUTURE, T, API)                                                              \
    AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API)                                                                        \
    API struct FUTURE *FUTURE##_new(struct aws_allocator *alloc);                                                      \
    API void FUTURE##_set_result(struct FUTURE *future, T result);                                                     \
    API T FUTURE##_get_result(const struct FUTURE *future);                                                            \
    AWS_FUTURE_T_DECLARATION_END(FUTURE, API)

#define AWS_FUTURE_T_BY_VALUE_IMPLEMENTATION(FUTURE, T)                                                                \
    AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)                                                                          \
    struct FUTURE *FUTURE##_new(struct aws_allocator *alloc) {                                                         \
        return (struct FUTURE *)aws_future_impl_new_by_value(alloc, sizeof(T));                                        \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_result(struct FUTURE *future, T result) {                                                        \
        aws_future_impl_set_result_by_move((struct aws_future_impl *)future, &result);                                 \
    }                                                                                                                  \
                                                                                                                       \
    T FUTURE##_get_result(const struct FUTURE *future) {                                                               \
        return *(T *)aws_future_impl_get_result_address((const struct aws_future_impl *)future);                       \
    }                                                                                                                  \
    AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)

/**
 * Declares a future that holds T by value, with destructor like: void aws_T_clean_up(T*)
 * Use with types like aws_byte_buf.
 *
 * See top of future.h for docs.
 */
#define AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP_DECLARATION(FUTURE, T, API)                                                \
    AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API)                                                                        \
    API struct FUTURE *FUTURE##_new(struct aws_allocator *alloc);                                                      \
    API void FUTURE##_set_result_by_move(struct FUTURE *future, T *value_address);                                     \
    API T *FUTURE##_peek_result(const struct FUTURE *future);                                                          \
    API T FUTURE##_get_result_by_move(struct FUTURE *future);                                                          \
    AWS_FUTURE_T_DECLARATION_END(FUTURE, API)

#define AWS_FUTURE_T_BY_VALUE_WITH_CLEAN_UP_IMPLEMENTATION(FUTURE, T, CLEAN_UP_FN)                                     \
    AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)                                                                          \
                                                                                                                       \
    struct FUTURE *FUTURE##_new(struct aws_allocator *alloc) {                                                         \
        void (*clean_up_fn)(T *) = CLEAN_UP_FN; /* check clean_up() function signature */                              \
        return (struct FUTURE *)aws_future_impl_new_by_value_with_clean_up(                                            \
            alloc, sizeof(T), (aws_future_impl_result_clean_up_fn)clean_up_fn);                                        \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_result_by_move(struct FUTURE *future, T *value_address) {                                        \
        aws_future_impl_set_result_by_move((struct aws_future_impl *)future, value_address);                           \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_peek_result(const struct FUTURE *future) {                                                             \
        return aws_future_impl_get_result_address((const struct aws_future_impl *)future);                             \
    }                                                                                                                  \
                                                                                                                       \
    T FUTURE##_get_result_by_move(struct FUTURE *future) {                                                             \
        T value;                                                                                                       \
        aws_future_impl_get_result_by_move((struct aws_future_impl *)future, &value);                                  \
        return value;                                                                                                  \
    }                                                                                                                  \
                                                                                                                       \
    AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)

/**
 * Declares a future that holds T*, with no destructor.
 *
 * See top of future.h for docs.
 */
#define AWS_FUTURE_T_POINTER_DECLARATION(FUTURE, T, API)                                                               \
    AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API)                                                                        \
    API struct FUTURE *FUTURE##_new(struct aws_allocator *alloc);                                                      \
    API void FUTURE##_set_result(struct FUTURE *future, T *result);                                                    \
    API T *FUTURE##_get_result(const struct FUTURE *future);                                                           \
    AWS_FUTURE_T_DECLARATION_END(FUTURE, API)

#define AWS_FUTURE_T_POINTER_IMPLEMENTATION(FUTURE, T)                                                                 \
    AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)                                                                          \
                                                                                                                       \
    struct FUTURE *FUTURE##_new(struct aws_allocator *alloc) {                                                         \
        return (struct FUTURE *)aws_future_impl_new_pointer(alloc);                                                    \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_result(struct FUTURE *future, T *result) {                                                       \
        aws_future_impl_set_result_by_move((struct aws_future_impl *)future, &result);                                 \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_get_result(const struct FUTURE *future) {                                                              \
        return *(T **)aws_future_impl_get_result_address((const struct aws_future_impl *)future);                      \
    }                                                                                                                  \
                                                                                                                       \
    AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)

/**
 * Declares a future that holds T*, with destructor like: void aws_T_destroy(T*)
 * Use with types like aws_string.
 *
 * See top of future.h for docs.
 */
#define AWS_FUTURE_T_POINTER_WITH_DESTROY_DECLARATION(FUTURE, T, API)                                                  \
    AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API)                                                                        \
    API struct FUTURE *FUTURE##_new(struct aws_allocator *alloc);                                                      \
    API void FUTURE##_set_result_by_move(struct FUTURE *future, T **pointer_address);                                  \
    API T *FUTURE##_get_result_by_move(struct FUTURE *future);                                                         \
    API T *FUTURE##_peek_result(const struct FUTURE *future);                                                          \
    AWS_FUTURE_T_DECLARATION_END(FUTURE, API)

#define AWS_FUTURE_T_POINTER_WITH_DESTROY_IMPLEMENTATION(FUTURE, T, DESTROY_FN)                                        \
    AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)                                                                          \
                                                                                                                       \
    struct FUTURE *FUTURE##_new(struct aws_allocator *alloc) {                                                         \
        void (*destroy_fn)(T *) = DESTROY_FN; /* check destroy() function signature */                                 \
        return (struct FUTURE *)aws_future_impl_new_pointer_with_destroy(                                              \
            alloc, (aws_future_impl_result_destroy_fn *)destroy_fn);                                                   \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_result_by_move(struct FUTURE *future, T **pointer_address) {                                     \
        aws_future_impl_set_result_by_move((struct aws_future_impl *)future, pointer_address);                         \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_get_result_by_move(struct FUTURE *future) {                                                            \
        T *pointer;                                                                                                    \
        aws_future_impl_get_result_by_move((struct aws_future_impl *)future, &pointer);                                \
        return pointer;                                                                                                \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_peek_result(const struct FUTURE *future) {                                                             \
        return *(T **)aws_future_impl_get_result_address((const struct aws_future_impl *)future);                      \
    }                                                                                                                  \
                                                                                                                       \
    AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)

/**
 * Declares a future that holds T*, with destructor like: T* aws_T_release(T*)
 * Use with types like aws_http_message
 *
 * See top of future.h for docs.
 */
#define AWS_FUTURE_T_POINTER_WITH_RELEASE_DECLARATION(FUTURE, T, API)                                                  \
    AWS_FUTURE_T_DECLARATION_BEGIN(FUTURE, API)                                                                        \
    API struct FUTURE *FUTURE##_new(struct aws_allocator *alloc);                                                      \
    API void FUTURE##_set_result_by_move(struct FUTURE *future, T **pointer_address);                                  \
    API T *FUTURE##_get_result_by_move(struct FUTURE *future);                                                         \
    API T *FUTURE##_peek_result(const struct FUTURE *future);                                                          \
    AWS_FUTURE_T_DECLARATION_END(FUTURE, API)

#define AWS_FUTURE_T_POINTER_WITH_RELEASE_IMPLEMENTATION(FUTURE, T, RELEASE_FN)                                        \
    AWS_FUTURE_T_IMPLEMENTATION_BEGIN(FUTURE)                                                                          \
                                                                                                                       \
    struct FUTURE *FUTURE##_new(struct aws_allocator *alloc) {                                                         \
        T *(*release_fn)(T *) = RELEASE_FN; /* check release() function signature */                                   \
        return (struct FUTURE *)aws_future_impl_new_pointer_with_release(                                              \
            alloc, (aws_future_impl_result_release_fn *)release_fn);                                                   \
    }                                                                                                                  \
                                                                                                                       \
    void FUTURE##_set_result_by_move(struct FUTURE *future, T **pointer_address) {                                     \
        aws_future_impl_set_result_by_move((struct aws_future_impl *)future, pointer_address);                         \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_get_result_by_move(struct FUTURE *future) {                                                            \
        T *pointer;                                                                                                    \
        aws_future_impl_get_result_by_move((struct aws_future_impl *)future, &pointer);                                \
        return pointer;                                                                                                \
    }                                                                                                                  \
                                                                                                                       \
    T *FUTURE##_peek_result(const struct FUTURE *future) {                                                             \
        return *(T **)aws_future_impl_get_result_address((const struct aws_future_impl *)future);                      \
    }                                                                                                                  \
                                                                                                                       \
    AWS_FUTURE_T_IMPLEMENTATION_END(FUTURE)

/**
 * aws_future<size_t>
 * See top of future.h for docs.
 */
AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_size, size_t, AWS_IO_API)

/**
 * aws_future<bool>
 * See top of future.h for docs.
 */
AWS_FUTURE_T_BY_VALUE_DECLARATION(aws_future_bool, bool, AWS_IO_API)

/**
 * aws_future<void>
 * See top of future.h for docs.
 */
AWS_FUTURE_T_DECLARATION_BEGIN(aws_future_void, AWS_IO_API)

AWS_IO_API struct aws_future_void *aws_future_void_new(struct aws_allocator *alloc);

AWS_IO_API void aws_future_void_set_result(struct aws_future_void *future);

AWS_FUTURE_T_DECLARATION_END(aws_future_void, AWS_IO_API)

AWS_EXTERN_C_END
AWS_POP_SANE_WARNING_LEVEL

#endif /* AWS_IO_FUTURE_H */
